getaddrinfo

getaddrinfo translates the name of a service location, for instance host name and/or a service name, and returns a set of socket addresses and associated information to be used in creating a socket to which specified service can be addressed.

Syntax

int WSAAPI getaddrinfo(
    __in const char *nodename,
    __in const char *servname,
    __in const struct addrinfo *hints,
    __out struct addrinfo **res
);

Parameters

nodename

A pointer to a zero terminated ASCII string containing a host (node) name or a numeric host address string. The numeric host address string is a dotted-decimal IPv4 address or an IPv6 hex address. If nodename is not null, the requested service location is named by nodename; otherwise, the requested service location is local to the caller.

servname

A pointer to a zero-terminated ASCII string containing either a service name or port number.

hints

A pointer to an addrinfo structure that provides hints about the type of socket the caller supports.

The ai_flags field to which the hints parameter points shall be set to zero or be bitwise-inclusive OR of one or more of the following values:

If AI_PASSIVE is specified, the returned address information is suitable for use in binding a socket for accepting incoming connections for the specified service (that is, a call to bind). This flag is ignored if the nodename argument is not null.

If AI_CANONNAME is specified and the nodename argument is not null, the function shall attempt to determine the canonical name corresponding to nodename.

If AI_NUMERICHOST is specified, then a non-null nodename string supplied shall be a numeric host address string. Otherwise, an EAI_NONAME error is returned. This flag shall prevent any type of name resolution service (for example, the DNS) from being invoked.

If AI_ADDRCONFIG is specified, IPv4 addresses shall be returned only if an IPv4 address is configured on the local system, and IPv6 addresses shall be returned only if an IPv6 address is configured on the local system.

res

A pointer to a linked list of one or more addrinfo structures containing response information about the host.

Return Values

0 (zero) if the function succeeds, a non-zero, positive value if the function fails

Error codes returned by getaddrinfo can also map to any of following:

Error Code	Description
EAI_AGAIN	The name server returned a temporary failure indication. Try again later.
EAI_BADFLAGS	ai_flags contains invalid flags.
EAI_FAMILY	The requested address family is not supported.
EAI_MEMORY	Memory allocation failure.
EAI_NONAME	The node or service is not known. This error is also returned if both node and service are NULL.
EAI_SERVICE	The requested service is not available for the requested socket type. It may be available through another socket type.
EAI_SOCKTYPE	The requested socket type is not supported.
EAI_FAIL	The name server returned a permanent failure indication.

Remarks

freeaddrinfo must be called when the application finishes using the pointer or a memory leak will occur.

| |